## Sound Functions -- Detailed Descriptions

### INDEX

#### Sound Functions -- Detailed Descriptions

      (1) Initialization of Sound Functions
          void m4aSoundInit(void);
      (2) Setting Up the Sound Function Operating Modes
          void m4aSoundMode(u32 mode);
      (3) Sound Driver Main Loop
          void m4aSoundMain(void);
      (4) Sound DMA Session Settings
          void m4aSoundVSync(void);
      (5) Stopping the Sound DMA
          void m4aSoundVSyncOff(void);
      (6) Restarting the Sound DMA
          void m4aSoundVSyncOn(void);
      (7) Starting a Performance Using a Song Title
          void m4aMPlayStart(MusicPlayerArea *&m4a_mplay???, SongHeader *SongName);
      (8) Starting a Performance Using a Song Number
          void m4aSongNumStart(u16 n);
      (9) Starting or Changing a Performance Using a Song Number
          void m4aSongNumStartOrChange(u16 n);
    (10) Starting or Restarting a Performance Using a Song Number
          void m4aSongNumStartOrContinue(u16 n);
    (11) Stopping (Pausing) a Song Performance
          void m4aMPlayStop(MusicPlayerArea *&m4a_mplay???);
    (12) Stopping (Pausing) a Performance Using a Song Number
          void m4aSongNumStop(u16 n);
    (13) Stopping (Pausing) the Performance of All Songs
          void m4aMPlayAllStop(void);
    (14) Restarting a Song Performance
          void m4aMPlayContinue(MusicPlayerArea *&m4a_mplay???);
    (15) Restarting a Performance Using a Song Number
          void m4aSongNumContinue(u16 n);
    (16) Restarting All Song Performances
          void m4aMPlayAllContinue(void);
    (17) Fading Out Songs
          void m4aMPlayFadeOut(MusicPlayerArea *&m4a_mplay???, u16 sp);
    (18) Changing the Tempo
          void m4aMPlayTempoControl(MusicPlayerArea *&m4a_mplay???, u16 te);
    (19) Changing the Volume
          void m4aMPlayVolumeControl(MusicPlayerArea *&m4a_mplay???, u16 tb, u16 vo);
    (20) Changing the Scale
          void m4aMPlayPitchControl(MusicPlayerArea *&m4a_mplay???, u16 tb, s16 pi);
    (21) Changing the Normal Position
          void m4aMPlayPanpotControl(MusicPlayerArea *&m4a_mplay???, u16 tb, s8 pa);
    (22) Changing the Modulation Depth
          void m4aMPlayModDepthSet(MusicPlayerArea *&m4a_mplay???, u16 tb, u8 md);
    (23) Changing the LFO Speed
          void m4aMPlayLFOSpeedSet(MusicPlayerArea *&m4a_mplay???, u16 tb, u8 ls);
    (24) Immediately Initialize the Song that is Going to Play
          void m4aMPlayImmInit(MusicPlayerArea *&m4a_mplay???);
    (25) Other Variables

#### (1) Initialization of Sound Functions

`void m4aSoundInit(void);`

This initializes the sound functions. Only call this once when starting up a game.
Return to Top

#### (2) Setting Up the Sound Function Operating Modes

`void m4aSoundMode(u32 mode);`

This sets up the sound function operating modes. The argument, mode, contains the following values.
Note: The following values for SOUND_MODE_xxxx_xxxx are constants defined in AgbSound.h.

       *Direct Sound Reverb
     mode = SOUND_MODE_REVERB_SET + ( Reverb Value: 0 to 127 );

       *Number of Simultaneously Produced Direct Sounds
            mode = ( Number of Simultaneously-Produced Sounds: 1 to 12 )
              << SOUND_MODE_MAXCHN_SHIFT;

       *Direct Sound Master Volume
            mode = ( Volume: 1 to 15 ) << SOUND_MODE_MASVOL_SHIFT;

       *Direct Sound Playback Frequency
            mode = SOUND_MODE_FREQ_?????;
                   The value ????? is defined in AgbSound.h.  (There are 12 types.)

       *Number of Final Output D/A Conversion Bits
            mode = SOUND_MODE_DA_BIT_?;
                   The ? range: 9 to 6

       (The above values may be set up at the same time using OR.)

Use the external variable sound_mode_i to return the operating mode to its original settings.

(Program Example)
`...`
`m4aSoundMode(sound_mode_i);`
`...`

Return to Top

#### (3) Sound Driver Main Loop

`void m4aSoundMain(void);`

This is the main loop of the sound driver. Call it every 1/60 of a second.
The process flow works as follows. m4aSoundVSync()(mentioned below) is called immediately after the V-Blank interrupt. Then after running BG or OBJ processes, this routine is called.

Return to Top

#### (4) Sound DMA Session Settings

`void m4aSoundVSync(void);`

This is an extremely short function that resets the DMA used in the sound to 1/60 of a second. The timing is very stringent, so call this "Immediately After" getting the V-Blank interrupt that comes at 1/60-second intervals.

Return to Top

#### (5) Stopping the Sound DMA

`void m4aSoundVSyncOff(void);`

When stopping the V-Blank interrupt for the main program or for some other reason, or when it becomes no longer possible to call m4a SoundVSync() every 1/60 of a second, this function has t o be used to stop the sound DMA. If it is not, the DMS will not stop even if the transfer buffer becomes overloaded, and a terrible noise will result. Also, if DMA1, DMA2, or Timer 0 is used for another purpose when the sound DMA is stopped, it will become impossible to restart this system. In this case it will be necessary to re-initialize using m4aSoundInit().

Return to Top

#### (6) Restarting the Sound DMA

`void m4aSoundVSyncOn(void);`

This function restarts the sound DMA when it has been stopped with m4aSoundVSyncOff(). Within 1/60 of a second of callin g this function, the V-Blank interrupt will take effect, and call m4aSoundVSync().

Return to Top

#### (7) Starting a Performance Using a Song Title

`void m4aMPlayStart(MusicPlayerArea *&m4a_mplay???, SongHeader *SongName);`

Music Player number ??? is used to perform the song data in the song title Songname.
(??? is a three-digit number, while Songname is the name of a file.)
(*It is also possible to write &m4a_mplay??? as mplay_table[???].ma.)

(Sample Program)
`...`
`// Start the song SongName using the Number 1 Music Player.`
`m4aMPlayStart(&m4a_mplay001, SongName);`
`...`

Note: In order to find out what song is playing currently on the music player, refer to the structural element m4a_mplay???.song in the work area.

(Sample Program)
`...`
`// Substitute the song name playing on Music Player 2 into the variable whatsong.`
`(SongHeader *)whatsong = m4a_mplay001.song;`
`...`

Also, in order to find out whether or not a song is currently playing on the Music Player, refer to the structural element m4a_mplay???.stat in the work area.

(Sample Program)
`...`
`if ( (m4a_mplay001.stat & MUSICPLAYER_STATUS_TRACK) == 0 )`
`{`
`// The track currently being played does not exist.`

`if ( (m4a_mplay001.stat & MUSICPLAYER_STATUS_PAUSE) != 0 )`
`{`
`// The performance has been stopped (paused).`
`}`
`else`
`{`
`// The performance on all tracks is complete.`
`}`
`}`
`else`
`{`
`//The track with the standing bit is being played.`
`// ( bit0 = Track1, bit1 = Track2, ...)`
`}`
`...`

Return to Top

#### (8) Starting a Performance Using a Song Number

`void m4aSongNumStart(u16 n);`

This starts playing the song with song number n. In this case, the Music Player to be used is already specified in the sound editor, so it is not necessary when this function is called.

(Sample Program)
`...`
`//This starts playing the song with song number x.`
`m4aSongNumStart( x );`
`...`

Note: The number of the Music Player used by the song with the song number x can be obtained using song_table[x].ms. The work area of the Music Player with that number (???) can be obtained using mplay_table[???].ma.

Return to Top

#### (9) Starting or Changing a Performance Using a Song Number

`void m4aSongNumStartOrChange(u16 n);`

This function starts playing the specified song when a different song is being played on the Music Player that is supposed to play the song with the song number n, or when the same song is currently stopped. When the same song is already being played, it does not do anything.

Return to Top

#### (10) Starting or Restarting a Perfomance Using a Song Number

`void m4aSongNumStartOrContinue(u16 n);`

This function starts playing a new song when a different song has been playing on the Music Player that is supposed to be playing song number n. When that song has been stopped, this function will restart it. When the same song is already being played, it does not do anything.

Return to Top

#### (11) Stopping (Pausing) a Song Performance

`void m4aMPlayStop(MusicPlayerArea *&m4a_mplay???);`

This stops the song being played on Music Player number ???. (??? is a three-digit number)
Note: The sound that is output will actually be stopped the next time that m4aSoundMain() is called.

Return to Top

#### (12) Stopping (Pausing) a Song Performance Using a Song Number

`void m4aSongNumStop(u16 n);`

In the event that song number n was already playing on the specified Music Player, the song will be stopped. If the song being played is not number n, it will not do anything. Note that the sound that is output will actually be stopped the next time that m4aSoundMain() is called.

Return to Top

#### (13) Stopping (Pausing) the Performance of All Songs

`void m4aMPlayAllStop(void);`

This stops all Music Players (set up with this system).
Note: The sound that is output will actually be stopped the next time that m4aSoundMain() is called.

Return to Top

#### (14) Restarting a Song Performance

`void m4aMPlayContinue(MusicPlayerArea *&m4a_mplay???);`

This restarts the song being played by the Music Player number ???. (??? is a three-digit number.)

Return to Top

#### (15) Restarting a Performance Using a Song Number

`void m4aSongNumContinue(u16 n);`

When song number n has been stopped on the specified music player, the performance will be restarted.
If the song that is stopped is not number n, nothing will happen.

Return to Top

#### (16) Restarting All Song Performances

`void m4aMPlayAllContinue(void);`

All Music Players (set up using this system) will resume playing.

Return to Top

#### (17) Fading Out Songs

`void m4aMPlayFadeOut(MusicPlayerArea *&m4a_mplay???, u16 sp);`

This function stops play after fading out the song running on number ??? Music Player at speed sp.
The time it takes to stop is ( sp * 16 / 60 ) of a second.

Note: m4aMPlayVolumeControl() (described below) cannot be used while using this fade out function.

Return to Top

#### (18) Changing the Tempo

`void m4aMPlayTempoControl(MusicPlayerArea *&m4a_mplay???, u16 te);`

This changes the tempo of the song being played on Music Player number ??? to ( te/256 ) times its original speed.
(This is not compounded each time it is called.)

Return to Top

#### (19) Changing the Volume

`void m4aMPlayVolumeControl(MusicPlayerArea *&m4a_mplay???, u16 tb, u16 vo);`

This changes the original volume corresponding to the bit specified in tb of the song being played on Music Player number ??? to ( vo/256 ) time. (This is not compounded each time it is called.)
The effective vo bits are from bit2 to bit9 and these can be set in a range between 0.0156 times and 3.98 times.
Note: The sound that is output will actually be changed the next time that m4aSoundMain() is called.
Note also that this function cannot be used during fade outs using m4aMPlayFadeOut().

(Sample Program)
`...`
`// This will double the volume on tracks 1 and 3 of Music Player number 3.`
`m4aMPlayVolumeControl(&m4a_mplay003, 0x05, 2*256);`
`...`

Return to Top

#### (20) Changing the Scale

`void m4aMPlayPitchControl(MusicPlayerArea *&m4a_mplay???, u16 tb, s16 pi);`

This adds the value pi (half tone=256) to the interval of the track corresponding to the bit specified in tb for the song being played by Music Player number ???. (This is not added every time it is called.)
pi = 0 restores it to the original scale.
Note: The sound that is output will actually be changed the next time that m4aSoundMain() is called.

Return to Top

#### (21) Changing the Normal Position

`void m4aMPlayPanpotControl(MusicPlayerArea *&m4a_mplay???, u16 tb, s8 pa);`

This adds the value pa/2 to the panpot (the normal position between the left and right) of the original track corresponding to the bit specified using tb for the song being played by Music Player number ???. (This will not be added every time it is called.)
The range of settings for pa is -128 to +127. pa = 0 will restore the original normal position.
Note: The sound that is output will actually be changed the next time that m4aSoundMain() is called.

Return to Top

#### (22) Changing the Modulation Depth

`void m4aMPlayModDepthSet(MusicPlayerArea *&m4a_mplay???, u16 tb, u8 md);`

This changes the modulation depth of the track corresponding to the bit specified using tb for the song being played by Music Player number ??? to the value md. Also note that the sound that is output will actually be changed the next time that m4aSoundMain() is called.

Return to Top

#### (23) Changing the LFO Speed

`void m4aMPlayLFOSpeedSet(MusicPlayerArea *&m4a_mplay???, u16 tb, u8 ls);`

This changes the LFO Speed of the track corresponding to the bit specified using tb for the song being played on Music Player number ??? to the value ls. The period for one quarter-note beat is ( ls * 24 / 256 ) times.

Return to Top

#### (24) Immediately Initialize the Song that is Going to Play

`void m4aMPlayImmInit(MusicPlayerArea *&m4a_mplay???);`

This immediately initializes the parameters of each track for the song you plan on performing with Music Player number ???.(??? is a three digit number)
Usually, after the song start function is called, each track's parameters are actually initialized the next time m4aSoundMain() is called. Thus, even if you call the parameter change function previous to this it has no effect. However, if you call the parameter change function after calling this function it will be effective.

Return to Top

#### (25) Other Variables

The following constants are declared as usable variables with the sound driver.
`u8 total_mplay_n` Total number of declared Music Players.
`u8 total_song_n` Total number of declared Songs
Return to Top

Next:[ Maximum Processing Time for m4aSoundMain( ) ]
Back:[ Song Data Tracks]
Top :[ Table of Contents ]